Header:

Some of the effects use || so make sure the `arrow' feature is loaded. ( <#8#>arrow<#8#> )

3 ( )

A polygon is most easily specified using ...
#defs11#
Here ;SPMlt;number;SPMgt; is a sequence of digits, giving the number of sides. If used within an ||...|| environment then the polygon will be centred on c, the current ;SPMlt;pos;SPMgt;. However an || can be used outside such an environment, as ``stand-alone'' polygon; the whole picture must be specified within the || command.

In either case the shape is obtained by spacing vertices equally around the ``unit circle'' with respect to the current basis. If this basis is non-square then the vertices will lie on an ellipse. Normally the polygon, with at most 12 vertices, is oriented so as to have a flat base when specified using a standard square basis. With more than 12~vertices the orientation is such that the line from the centre to the first vertex is horizontal, pointing to the right. Any other desired orientation can be obtained, with any number of vertices, by using the |~=<#16#>|...|<#16#>| as described below.

The general form for || is ...
#defs117#
where the |;SPMquot;|;SPMlt;prefix;SPMgt;|;SPMquot;| and ;SPMlt;switches;SPMgt; are optional. Their uses will be described shortly.

A || establishes positions for the vertices of a polygon. At the same time various things may be typeset, according to the specified ;SPMlt;switches;SPMgt;. An ;SPMlt;object;SPMgt; may be dropped at each vertex, ``spokes'' drawn to the centre and successive vertices may be connected as the polygon's ``sides''. Labels and breaks can be specified along the spokes and sides.

Each vertex is automatically named: |;SPMquot;1;SPMquot;|, |;SPMquot;2;SPMquot;|, ..., |;SPMquot;|;SPMlt;number;SPMgt;|;SPMquot;| with |;SPMquot;0;SPMquot;| as centre. When a ;SPMlt;prefix;SPMgt; has been given, names |;SPMquot;|;SPMlt;prefix;SPMgt;|0;SPMquot;|, ..., |;SPMquot;|;SPMlt;prefix;SPMgt;;SPMlt;number;SPMgt;|;SPMquot;| are used instead. While the polygon is being constructed the macro || expands to the number of sides, while || expands to the number of each vertex, spoke and side at the time it is processed. This occurs in the following order: <#20#>vertex<#20#> 1, <#21#>spoke<#21#> 1, <#22#>vertex<#22#> 2, <#23#>spoke<#23#> 2, <#24#>side<#24#> 1, <#25#>vertex<#25#> 3, <#26#>spoke<#26#> 3, <#27#>side<#27#> 2, ..., <#28#>vertex<#28#> n, <#29#>spoke<#29#> n, <#30#>side<#30#> n - 1, <#31#>side<#31#> n where the final side joins the last vertex to the first.

The macro || holds the name of the polygon, which is ;SPMlt;prefix;SPMgt; if supplied. In this case the value of || is also stored as |||;SPMlt;prefix;SPMgt;|NUMSIDES|, accessible outside the polygon.

As stated above, a polygon with up to 12 vertices is oriented so as to have a flat base, when drawn using a standard square basis. Its vertices are numbered in anti-clockwise order, commencing with the one at horizontal-right of centre, or the smallest angle above this (see example below). With more than 12 vertices then vertex |;SPMquot;1;SPMquot;| is located on the horizontal, extending to the right from centre (assuming a standard square basis). By providing a switch of the form |~=<#32#>|;SPMlt;angle;SPMgt;|<#32#>| then the vertex |;SPMquot;1;SPMquot;| will be located on the unit circle at ;SPMlt;angle;SPMgt;^o anti-clockwise from ``horizontal'' --- more correctly, from the X-direction in the basis to be used when setting the polygon, which may be established using a |~:<#33#>|...|<#33#>| switch.

#code34#

#math363#

#tex2html_wrap_indisplay1241#

#exercise46#

One important use of ;SPMlt;prefix;SPMgt; is to allow the vertices of more than one polygon to be accessed subsequently within the same picture. Here are some examples of this, incorporating the |~:<#49#>|...|<#49#>| switch to perform simple rescalings. Firstly the edges of a dodecahedron as a planar graph:

#code50#

#math364#

#tex2html_wrap_indisplay1243#

Next a hexagonal pyramid, a rectangular box and an octahedral crystal specified as a triangular anti-prism. Notice how the |~:<#68#>|...|<#68#>| switch is used to create non-square bases, allowing the illusion of 3D-perspective in the resulting diagrams:

#code69#

#math365#

#tex2html_wrap_indisplay1245#

2 || simply reads the value of a counter called |@|. It is set initially at -1, to indicate no polygon yet. This is used to establish the default naming in case polygons are nested.

( @<#82#>count<#82#>@@=@ne @<#83#>@<#83#>

@@ <#84#><#84#> @<#85#>@ <#85#> )

To allow recursion the values of |@ | and |@| are saved upon entering an ||, to be restored at the end.

( @<#86#>@<#86#>34

@@<#823#>35 @ @ @<#806#>@@<#769#>@<#651#>@=@ne<#651#><#769#><#806#>38 @ @<#808#>@@<#771#>@<#653#>@=@ne <#653#><#771#><#808#>41 @ @=@ @@n<#823#>

@@ <#93#>TF<#93#>42 @@x<#654#>@@<#94#>@@<#94#><#654#> )

Read the number of vertices by parsing digits.

( @@n<#655#>43 @##1<#95#>@10@##1@@n<#95#>44 @ @;SPMgt;@ @ @<#96#>@@i<#96#>45 @ @<#97#>@@n<#97#> 0123 4567 89 @ =@i @ <#655#>

@@i<#656#>@@<#656#> )

Next we check whether a prefix has been supplied for creating the vertex names. If so it is stored as |@|, which otherwise expands to empty. The number of sides is also stored using the prefix.

( @@<#99#><#99#>46 @@@ <#100#><#100#>47 @<#101#>@<#101#>48

@@<#772#>49 ;SPMquot;@;SPMquot;##1;SPMquot;<#657#> @@ <#657#>51 @;SPMlt;@ @<#106#>@@<#106#>54 @ <#772#>

@@@<#809#>55 @<#107#>@;SPMquot;<#107#>56 @<#108#>@@ 0;SPMquot;<#108#>57 @ @;SPMlt;@ @@<#773#>@<#658#>@=@ <#658#>@=@ <#773#>59 @@<#774#>@<#659#>@=@ <#659#>@=@ <#774#>60 @@i <#809#> )

Currently any tokens remaining before the opening brace are discarded, with an accompanying message.

( @@@i#1#<#660#> @<#113#>#1<#113#>@ @<#114#>discarding unused tokens: #1<#114#>@@ <#660#> )

Next it is time to analyse the braced information, e.g. to set switches and/or adjust the scale. If this information is empty |<#115#><#115#>| then the default values are used.

( @@@#1<#661#>@ @<#116#>#1<#116#>@ @<#117#>@@@<#117#>62 @<#118#>@@#1~!<#118#>@ <#661#>

@@<#775#>@ @ <#775#> )